home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 22 / AACD 22.iso / AACD / Utilities / MCControl / Bonus / Developer / Modules / Modules.doc < prev    next >
Encoding:
Text File  |  2001-04-11  |  12.7 KB  |  338 lines
  1. ;----------------------------------------------------------------------------
  2. ; $VER: MCControlModule.Doc 1.40 (19.02.2000)
  3. ;----------------------------------------------------------------------------
  4. ;This is not an documentation how to use the .mcm modules in your own
  5. ;software! Its an documentation about how to write modules for other
  6. ;card reader.
  7. ;----------------------------------------------------------------------------
  8. TABLE OF CONTENTS
  9.  
  10. MCControlModule/General
  11. MCControlModule/Module_Info
  12. MCControlModule/Module_Open
  13. MCControlModule/Module_Close
  14. MCControlModule/Module_AccessDirectFrame
  15. MCControlModule/Module_AccessDirectPage
  16. MCControlModule/Module_AccessRawFrame
  17. MCControlModule/Module_AccessRawPage
  18. ;----------------------------------------------------------------------------
  19.  
  20. First the main structure:
  21.  
  22. Module_Identifier       = "MCCM"
  23. Module_VersionNumber    = 1
  24.         RSRESET
  25. Module_Code                 rs.w 1 ;MUST $4e75 (RTS)
  26. Module_Version              rs.w 1 ;Must be Module_VersionNumber
  27. Module_ID                   rs.l 1 ;Must be "MCCM"
  28. Module_Flags                rs.l 1 ;see below (unused flags must be zero)
  29. Module_Exec_Base            rs.l 1 ;Filled by MCControl
  30. Module_Dos_Base             rs.l 1 ;Filled by MCControl
  31. Module_Intuition_Base       rs.l 1 ;Filled by MCControl
  32. ;--- Card Data
  33. Module_Reserved1            rs.l 14 ;Reserved (must be ZERO)
  34. ;--- Jump Table
  35. Module_Info                 rs.w 3
  36. Module_Open                 rs.w 3
  37. Module_Close                rs.w 3
  38. Module_ReservedFunctions2   rs.w 3*7 ;Reserved
  39. Module_AccessDirectFrame    rs.w 3
  40. Module_AccessDirectPage     rs.w 3
  41. Module_AccessRawFrame       rs.w 3
  42. Module_AccessRawPage        rs.w 3
  43. Module_ReservedFunctions3   rs.w 3*6 ;reserved
  44. Module_SIZEOF               rs.b 0
  45. ;----------------------------------------------------------------------------
  46. ;--- Enable transfer routines:
  47.  BITDEF Module,AccessDirectFrame,3  ;Driver supports DirectFrameAccess
  48.  BITDEF Module,AccessDirectPage,7   ;Driver supports DirectPageAccess
  49.  BITDEF Module,AccessRawFrame,6     ;Driver supports RawFrameAccess
  50.  BITDEF Module,AccessRawPage,8      ;Driver supports RawPageAccess
  51. ;--- Enable gadgets within the settings window:
  52.  BITDEF Module,ConfigMultiPage,5    ;Driver requires MultiPage setup
  53.  BITDEF Module,Reserved2,0          ;Must be Zero
  54.  BITDEF Module,ConfigDevice,1       ;Driver requires an Device/Unit selector
  55. ;--- Enable special functions:
  56.  BITDEF Module,EnableMultiPage,2    ;Turn on MultiPage support
  57.  BITDEF Module,EnableMultiSlot,4    ;Turn on MultiSlot support
  58.  BITDEF Module,EnableModuleInfo,9   ;Turn on ModuleInfo support
  59. ;----------------------------------------------------------------------------
  60. Module_Error_NoError       = 0
  61. Module_Error_OpenDevice    = 1 ;Opening the given device fails!
  62. Module_Error_NotCompatible = 2 ;If hardware supports identification!
  63. Module_Error_NoTimerDevice = 3 ;If you need the timer.device and opening fails
  64. Module_Error_NoParallelPort= 4 ;No ParallelPort resource
  65. Module_Error_NoResources   = 5 ;Use for missing signals, CIA Interrupts,...
  66. Module_Error_OutOfMemory   = 20
  67. ;----------------------------------------------------------------------------
  68. ;--- For AccessDirectFrame (Mode)
  69. Module_AccessDirect_Read    = 0
  70. Module_AccessDirect_Write   = 1
  71. ;--- For AccessDirectPage (Mode)
  72. Module_AccessDirect_Up      = 0
  73. Module_AccessDirect_Down    = 1
  74. ;----------------------------------------------------------------------------
  75. ;----------------------------------------------------------------------------
  76.  
  77.  NOTES 
  78.  
  79.    The exec, dos and intuition  bases  are  for  free  usage.  This  saves
  80.    memory,  time and of cource code size. The card data is for free usage,
  81.    too.
  82.  
  83.    Beside the arguments delivered for  each  function  you´ll  receive  an
  84.    pointer on the module itself in register A4!
  85.  
  86.    Make sure to backup a2-a5 and d2-d7 just like the Amiga-OS is doing!
  87.  
  88.    You must implement port and device allocation! Don´t try to  play  with
  89.    the  hardware without owning the right to do so. If possible try to use
  90.    parallel.device or serial.device. (The  user  defined  device  will  be
  91.    given during Module_Open().
  92.        
  93.    It´s not required to create an real  jumptable,  by  using  JMPs.  Feel
  94.    free, to use an BRA followed by an NOP. (See RamCard.mcm)
  95.        
  96.    Implement the code as fast as possible, because its used for many times
  97.    during reading and writing memory cards. Try to avoid overhead by using
  98.    Module_Open.
  99.  
  100.    If you need help then ask me and I´am telling you what to  do.  If  you
  101.    don´t  know how to code a driver then send me your information and I´ll
  102.    do my very best.
  103.  
  104. ;----------------------------------------------------------------------------
  105. ;----------------------------------------------------------------------------
  106. MCControlModule/Module_Info
  107.  
  108.    NAME
  109.                  Module_Info -- open and inits the module
  110.  
  111.    SYNOPSIS
  112.                  Error   = Module_Info(Buffer, BufferSize)
  113.                  D0                    a0,     d0
  114.  
  115.                  (ULONG) = Module_Open(*UBYTE, ULONG)
  116.  
  117.    FUNCTION
  118.                  Give MCControl special information about your driver,
  119.                  the hardware version detected or something like that.
  120.  
  121.    INPUTS
  122.                  Buffer:     Destination buffer for your message
  123.                  BufferSize: Size of the destinaton buffer! Make sure you
  124.                              don´t write more than these numbe of bytes!
  125.  
  126.    RESULT
  127.                   0 = No Error
  128.  
  129.                  Other results are currently not allowed!!
  130.  
  131.    NOTES
  132.                  Please support this routine! Even if there isn´t any
  133.                  important to say, then just report the version strings
  134.                  like shown in the example sources.
  135.  
  136.                  Buffer is garanted to be 100 bytes at minimum. If you are
  137.                  not sure your routine may create longer strings, then use
  138.                  BufferSize to not step over boundaries. The visible gadget
  139.                  space isn´t very big, so take an eye on this, too!
  140.  
  141.                  This function requires the flag: ModuleF_EnableModuleInfo!
  142.                  Otherwise MCControl is ignoring this routine.
  143.  
  144.    SEE ALSO
  145.                  Module_Close()
  146. ;----------------------------------------------------------------------------
  147. MCControlModule/Module_Open
  148.  
  149.    NAME
  150.                  Module_Open -- open and inits the module
  151.  
  152.    SYNOPSIS
  153.                  Error   = Module_Open(Device, Unit)
  154.                  D0                    a0,     d0
  155.  
  156.                  (ULONG) = Module_Open(*UBYTE,ULONG)
  157.  
  158.    FUNCTION
  159.                  Open the required device and alloc additional memory
  160.                  if needed.
  161.  
  162.    INPUTS
  163.                  Device: Pointer on device name (STRING IS READ ONLY!!!)
  164.                  Unit:   Unit of the given device
  165.  
  166.    RESULT
  167.                   0 = No Error
  168.                   1 = Open device error
  169.                   2 = Not compatible
  170.                   3 = time.device open error
  171.                   4 = No parallel resource
  172.                   5 = No resources (no signals, CIA interrupts)
  173.                  20 = Out of memory
  174.  
  175.                  Other results are currently not allowed!!
  176.  
  177.    NOTES
  178.                  Device and Unit are only valid if the ModuleF_ConfigDevice
  179.                  flag within the module structure (Module_Flags) is set.
  180.  
  181.    SEE ALSO
  182.                  Module_Close()
  183. ;----------------------------------------------------------------------------
  184. MCControlModule/Module_Close
  185.  
  186.    NAME
  187.                  Module_Close -- free all data and close all devices.
  188.  
  189.    SYNOPSIS
  190.                  Module_Close()
  191.  
  192.    FUNCTION
  193.                  Close all devices and free all allocated memory .
  194.  
  195.    NOTES
  196.                  Module_Close must be save to be called more than
  197.                  one time. This means you must detect an closing of
  198.                  an just closed module. In this case you must return
  199.                  without any action.
  200.  
  201.    SEE ALSO
  202.                  Module_Open()
  203. ;----------------------------------------------------------------------------
  204. MCControlModule/Module_AccessDirectFrame
  205.  
  206.    NAME
  207.                  Module_AccessDirectFrame -- Handles a comlete frame at once
  208.  
  209.    SYNOPSIS
  210.                  Error   = Module_AccessDirectFrame(Frame,Mode,Data,Slot)
  211.                  D0                                 D0,   D1,  A0  ,A1
  212.  
  213.                  (LONG)  = Module_AccessDirectFrame(WORD, LONG,*Byte,WORD)
  214.  
  215.    INPUTS
  216.                  Frame: Frame number to read or write!
  217.                  Mode:  Module_AccessDirect_Read or Module_AccessDirect_Write
  218.                  Data:  Pointer on Buffer!
  219.                  Slot:  Number of card slot (0-x)
  220.  
  221.    RESULT
  222.                   0 = Ok
  223.                  -1 = ERROR
  224.  
  225.                  Other results are currently not allowed!!
  226.  
  227.    FUNCTION
  228.                  Read or write the given frame (128 bytes)!
  229.  
  230.    NOTE
  231.                  Data must be 128 bytes long!
  232.                  This function requires the flag: ModuleF_AccessDirectFrame!
  233.                  Otherwise MCControl is ignoring this routine.
  234. ;----------------------------------------------------------------------------
  235. MCControlModule/Module_AccessDirectPage
  236.  
  237.    NAME
  238.                  Module_AccessDirectPage -- Handle page swapping
  239.  
  240.    SYNOPSIS
  241.                  Error   = AccessModule_DirectPage(Offset,Mode,Slot)
  242.                  D0                                D0,    D1  ,A1
  243.  
  244.                  (LONG)  = Module_AccessDDirectPage(WORD, LONG, WORD)
  245.  
  246.    INPUTS
  247.                  Offset: Number of pages to jump!
  248.                  Mode:   Module_AccessDirect_Next or Module_AccessDirect_Prev
  249.                  Slot:   Number of card slot (0-x)
  250.  
  251.    RESULT
  252.                   0 = Ok
  253.                  -1 = ERROR
  254.  
  255.                  Other results are currently not allowed!!
  256.  
  257.    FUNCTION
  258.                  Change the active card page of an multipage MemoryCard!
  259.  
  260.    NOTE
  261.                  This function requires the flag: ModuleF_AccessDirectPage!
  262.                  Otherwise MCControl is ignoring this routine.
  263.  
  264. ;----------------------------------------------------------------------------
  265. MCControlModule/Module_AccessRawFrame
  266.  
  267.    NAME
  268.                  Module_AccessRawFrame -- Raw handling of frame access
  269.  
  270.    SYNOPSIS
  271.                  Error   = Module_AccessRawFrame(Data ,Size,Flags,Slot)
  272.                  D0                              a0   ,D0  ,D1   ,A1
  273.  
  274.                  (LONG)  = Module_AccessRawFrame(*Byte,LONG,LONG,WORD)
  275.  
  276.    INPUTS
  277.                  Data:     Pointer on raw buffer
  278.                  Size:     Number of bytes in buffer
  279.                  Flags:    Currently always NULL
  280.                  Slot:     Number of card slot (0-x)
  281.  
  282.    RESULT
  283.                   0 = Ok
  284.                  -1 = ERROR
  285.  
  286.                  Other results are currently not allowed!!
  287.  
  288.    FUNCTION
  289.                  You´ll get a real playstation message for direct raw
  290.                  card access. Just take the first byte, put it to your
  291.                  reader and store the result where the source byte came
  292.                  from. Do this for each byte (size times). Thats all!
  293.                  MCControl handles the error checking for you!
  294.    NOTE
  295.                  This function requires the flag: ModuleF_AccessRawFrame
  296.                  Otherwise MCControl is ignoring this routine.
  297. ;----------------------------------------------------------------------------
  298. MCControlModule/Module_AccessRawPage
  299.  
  300.    NAME
  301.                  Module_AccessRawPage -- Raw handling of page access
  302.  
  303.    SYNOPSIS
  304.                  Error   = Module_AccessRawPage(Data ,Size,Flags,Slot)
  305.                  D0                             a0   ,D0  ,D1   ,A1
  306.  
  307.                  (LONG)  = Module_AccessRawPage(*Byte,LONG,LONG,WORD)
  308.  
  309.    INPUTS
  310.                  Data:     Pointer on raw buffer
  311.                  Size:     Number of bytes in buffer
  312.                  Flags:    Currently always NULL
  313.                  Slot:     Number of card slot (0-x)
  314.  
  315.    RESULT
  316.                   0 = Ok
  317.                  -1 = ERROR
  318.  
  319.                  Other results are currently not allowed!!
  320.  
  321.    FUNCTION
  322.                  You´ll get two messages mixed together. Your job is to
  323.                  put the first byte via CMD line into the card an the
  324.                  second byte at the same transfer via DAT. As you can see
  325.                  its required to output both information lines, so there
  326.                  is no need to store any result. The card is thinking its
  327.                  hearing an PSX and an PSX-Controller talking and browses
  328.                  through the pages. Size (Size) delivers the total number
  329.                  of bytes in buffer and you transfer 2 bytes at the same
  330.                  time, so just half this value to get the number of loop
  331.                  required for transfer.
  332.  
  333.    NOTE
  334.                  This function requires the flag: ModuleF_AccessRawPage
  335.                  Otherwise MCControl is ignoring this routine.
  336. ;----------------------------------------------------------------------------
  337.  
  338.